---
title: "Connecting Your AgentOS"
sidebarTitle: "Connect Your OS"
description: "Step-by-step guide to connect your local AgentOS to the AgentOS Control Plane"
---

## Overview

Connecting your AgentOS is the critical first step to using the AgentOS Control Plane. This process establishes a connection between your running AgentOS instance and the Control Plane, allowing you to manage, monitor, and interact with your agents through the browser.

<Note>
  **Prerequisites**: You need a running AgentOS instance before you can connect
  it to the Control Plane. If you haven't created one yet, check out our [Creating
  Your First OS](/agent-os/creating-your-first-os) guide.
</Note>

See the [AgentOS Control Plane](/agent-os/control-plane) documentation for more information about the Control Plane.

## Step-by-Step Connection Process

### 1. Access the Connection Dialog

In the Agno platform:

1. Click on the team/organization dropdown in the top navigation bar
2. Click the **"+"** (plus) button next to "Add new OS"
3. The "Connect your AgentOS" dialog will open

<Frame>
  <video
    autoPlay
    muted
    loop
    playsInline
    style={{ borderRadius: "0.5rem", width: "100%", height: "auto" }}
  >
    <source src="/videos/agent-os-connect-os.mp4" type="video/mp4" />
  </video>
</Frame>

### 2. Choose Your Environment

Select **"Local"** for development or **"Live"** for production:

- **Local**: Connects to an AgentOS running on your local machine
- **Live**: Connects to a production AgentOS running on your infrastructure

<Note>Live AgentOS connections require a PRO subscription.</Note>

### 3. Configure Connection Settings

#### Endpoint URL

- **Default Local**: `http://localhost:7777`
- **Custom Local**: You can change the port if your AgentOS runs on a different port
- **Live**: Enter your production HTTPS URL

<Warning>
  Make sure your AgentOS is actually running on the specified endpoint before
  attempting to connect.
</Warning>

#### OS Name

Give your AgentOS a descriptive name:

- Use clear, descriptive names like "Development OS" or "Production Chat Bot"
- This name will appear in your OS list and help you identify different instances

#### Tags (Optional)

Add tags to organize your AgentOS instances:

- Examples: `development`, `production`, `chatbot`, `research`
- Tags help filter and organize multiple OS instances
- Click the **"+"** button to add multiple tags

### 4. Test and Connect

1. Click the **"CONNECT"** button
2. The platform will attempt to establish a connection to your AgentOS
3. If successful, you'll see your new OS in the organization dashboard

## Verifying Your Connection

Once connected, you should see:

1. **OS Status**: "Running" indicator in the platform
2. **Available Features**: Chat, Knowledge, Memory, Sessions, etc. should be accessible
3. **Agent List**: Your configured agents should appear in the chat interface

## Securing Your Connection

Protect your AgentOS APIs and Control Plane access with bearer-token authentication. Security keys provide essential protection for both development and production environments.

**Key Features:**

- Generate unique security keys per AgentOS instance
- Rotate keys easily through the organization settings
- Configure bearer-token authentication on your server

<Frame>
  <video
    autoPlay
    muted
    loop
    playsInline
    style={{ borderRadius: "0.5rem", width: "100%", height: "auto" }}
  >
    <source src="/videos/agentos-security-key.mp4" type="video/mp4" />
  </video>
</Frame>

<Note>
  For complete security setup instructions, including environment configuration
  and best practices, see the [Security Key](/agent-os/security) documentation.
</Note>

## Managing Connected OS Instances

### Switching Between OS Instances

1. Use the dropdown in the top navigation bar
2. Select the OS instance you want to work with
3. All platform features will now connect to the selected OS

### Disconnecting an OS

1. Go to the organization settings
2. Find the OS in your list
3. Click the delete option

<Warning>
  Disconnecting an OS doesn't stop the AgentOS instance - it only removes it
  from the platform interface.
</Warning>

## Next Steps

Once your AgentOS is successfully connected:

<CardGroup cols={2}>
  <Card
    title="Explore the Chat Interface"
    icon="comment"
    href="/agent-os/features/chat-interface"
  >
    Start having conversations with your connected agents
  </Card>
  <Card
    title="Manage Knowledge"
    icon="brain"
    href="/agent-os/features/knowledge-management"
  >
    Upload and organize your knowledge bases
  </Card>
  <Card
    title="Monitor Sessions"
    icon="chart-line"
    href="/agent-os/features/session-tracking"
  >
    Track and analyze your agent interactions
  </Card>
</CardGroup>
